﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>Format - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The Format function formats a variable number of input values according to a format string." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>Format</h1>

<p>Formats a variable number of input values according to a format string.</p>

<pre class="Syntax">String := <span class="func">Format</span>(FormatStr <span class="optional">, Values...</span>)</pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>FormatStr</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>A format string composed of literal text and placeholders of the form <code>{<i>Index</i>:<i><a href="#FormatSpec">Format</a></i>}</code>.</p>
    <p><em>Index</em> is an integer indicating which input value to use, where 1 is the first value.</p>
    <p><em>Format</em> is an optional format specifier, as described below.</p>
    <p>Omit the index to use the next input value in the sequence (even if it has been used earlier in the string). 例如, <code>"{2:i} {:i}"</code> formats the second and third input values as decimal integers, separated by a space. If <em>Index</em> is omitted, <em>Format</em> must still be preceded by <code>:</code>. Specify empty braces to use the next input value with default formatting: <code>{}</code></p>
    <p>Use <code>{{}</code> and <code>{}}</code> to include literal braces in the string. Any other invalid placeholders are included in the result as is.</p>
    <p>Whitespace inside the braces is not permitted (except as a flag).</p>
  </dd>

  <dt>Values</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a>, <a href="../Concepts.htm#numbers">Integer</a> or <a href="../Concepts.htm#numbers">Float</a></p>
    <p>Input values to be formatted and inserted into the final string. Each value is a separate parameter. The first value has an index of 1.</p>
    <p>To pass an array of values, use a <a href="../Functions.htm#VariadicCall">variadic function call</a>:</p>
    <pre>arr := [13, 240]
MsgBox Format("{2:x}{1:02x}", arr*)</pre>
  </dd>

</dl>

<h2 id="Return_Value">返回值</h2>
<p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
<p>This function returns the formatted version of the specified string.</p>

<h2 id="FormatSpec">Format Specifiers</h2>
<p>Each format specifier can include the following components, in this order (without the spaces):</p>
<pre class="Syntax">Flags Width .Precision ULT Type</pre>
<p><a href="#Flags"><strong>Flags</strong></a> which affect output justification and prefixes: <code>-</code> <code>+</code> <code class="no-highlight">0</code> <code>&nbsp;</code> <code>#</code></p>
<p><strong>Width</strong>: a decimal integer which controls the minimum width of the formatted value, in characters. By default, values are right-aligned and spaces are used for padding. This can be overridden by using the <code>-</code> (left-align) and <code class="no-highlight">0</code> (zero prefix) flags.</p>
<p><strong>.Precision</strong>: a decimal integer which controls the maximum number of string characters, decimal places, or significant digits to output, depending on the output type. It must be preceded by a decimal point. Specifying a precision may cause the value to be truncated or rounded. Output types and how each is affected by the precision value are as follows (see table below for an explanation of the different output types):</p>
<ul>
  <li><code>f</code>, <code>e</code>, <code>E</code>: <em>Precision</em> specifies the number of digits after the decimal point. The default is 6.</li>
  <li><code>g</code>, <code>G</code>: <em>Precision</em> specifies the maximum number of significant digits. The default is 6.</li>
  <li><code>s</code>: <em>Precision</em> specifies the maximum number of characters to be printed. Characters in excess of this are not printed.</li>
  <li>For the integer types (<code>d</code>, <code>i</code>, <code>u</code>, <code>x</code>, <code>X</code>, <code>o</code>), <em>Precision</em> acts like <em>Width</em> with the <code class="no-highlight">0</code> prefix and a default of 1.</li>
</ul>
<p id="ULT"><b>ULT</b>: specifies a case transformation to apply to a string value -- <b>U</b>pper, <b>L</b>ower or <b>T</b>itle. Valid only with the <code>s</code> type. For example <code>{:U}</code> or <code>{:.20Ts}</code>. Lower-case <code>l</code> and <code>t</code> are also supported, but <code>u</code> is reserved for unsigned integers.</p>
<p><a href="#Types"><strong>Type</strong></a>: a character indicating how the input value should be interpreted. If omitted, it defaults to <code>s</code>.</p>

<table class="info" id="Flags">
  <tr><th>标志</th><th>含义</th></tr>
  <tr>
    <td><code>-</code></td>
    <td>
      <p>在给定位宽下使结果左对齐(不足位宽的右侧部分补以空格). 例如, <code>Format("{:-10}", 1)</code> 返回 <code class="no-highlight" style="white-space: pre">1         </code>.</p>
      <p>如果省略, 结果将在给定的位宽内右对齐.</p>
    </td>
  </tr>
  <tr>
    <td><code>+</code></td>
    <td>
      <p>如果输出值是带符号的类型, 则使用符号(+ 或 -) 作为前缀. 例如, <code>Format("{:+d}", 1)</code> 返回 <code class="no-highlight">+1</code>.</p>
      <p>如果省略, 仅在输出值是负数时显示符号(-).</p>
    </td>
  </tr>
  <tr>
    <td><code class="no-highlight">0</code></td>
   <td>
      <p>如果 <em>width</em> 以 0 为前缀, 前导 0 将被添加直至最小宽度. 例如, <code>Format("{:010}", 1)</code> 返回 <code class="no-highlight">0000000001</code>. 若同时使用 <code class="no-highlight">0</code> 和 <code>-</code>, 则前者将被忽略. 如果 0 被指定为整数格式(i, u, x, X, o, d) 且同时带有精度指示 - 例如, <code class="no-highlight">{:04.d}</code> - 此时的 0 会被忽略.</p>
      <p>如果省略, 不填充.</p>
    </td>
  </tr>
  <tr>
    <td><code>&nbsp;</code></td>
    <td>
      <p>当输出值是有符号数且为正数时, 以空格为前缀来修饰. 如果空格 <code>&nbsp;</code> 和 <code>+</code> 同时出现时, 空格将被忽略. 例如, <code>Format("{:&nbsp;10}", 1)</code> 返回 <code class="no-highlight" style="white-space: pre">         1</code>.</p>
      <p>如果省略, 无空格.</p>
    </td>
  </tr>
  <tr>
    <td><code>#</code></td>
    <td>
      <p>当 # 和 o, x 或 X 格式一起使用时, 此标志使用 <code class="no-highlight">0</code>, <code class="no-highlight">0x</code> 或 <code class="no-highlight">0X</code> 的形式分别修饰任意非零的输出值. 例如, <code>Format("{:#x}", 1)</code> 返回 <code class="no-highlight">0x1</code>.</p>
      <p>当 # 和 e, E, f, a, A 格式一起使用时, 此标志强制使输出值包含小数点. 例如, <code>Format("{:#.0f}", 1)</code> 返回 <code class="no-highlight">1.</code>.</p>
      <p>当 # 和 g 或 G 一起使用时, 此标志强制使输出值包含小数点并保留末尾的 0.</p>
      <p>当 # 和 c, d, i, u 或 s 格式一起使用时会被忽略.</p>
    </td>
    <td></td>
  </tr>
</table>
<table class="info" id="Types">
  <tr><th>Type Character</th><th style="min-width:7em">Argument</th><th>Output format</th></tr>
  <tr>
    <td><code>d</code> or <code>i</code></td>
    <td>Integer</td>
    <td>有符号整数. 例如, <code>Format("{:d}", 1.23)</code> 返回 <code class="no-highlight">1</code>.</td>
  </tr>
  <tr>
    <td><code>u</code></td>
    <td>Integer</td>
    <td>Unsigned decimal integer.</td>
  </tr>
  <tr>
    <td><code>x</code> or <code>X</code></td>
    <td>Integer</td>
    <td>无符号十六进制整数; 由 <code>x</code> 的大小写形式决定输出值是 "abcdef" 还是 "ABCDEF" 的形式, 仅当使用了 <code>#</code> 标志时, <code class="no-highlight">0x</code> 前缀才会包含到输出值中, 如 <code>{:#x}</code>. 要总是包含前缀, 请使用 <code class="no-highlight">0x{:x}</code> 或类似的. 例如, <code>Format("{:X}", 255)</code> 返回 <code>FF</code>.</td>
  </tr>
  <tr>
    <td><code>o</code></td>
    <td>Integer</td>
    <td>无符号八进制整数. 例如, <code>Format("{:o}", 255)</code> 返回 <code class="no-highlight">377</code>.</td>
  </tr>
  <tr>
    <td><code>f</code></td>
    <td>Floating-point</td>
    <td>形如 [ - ]<em>dddd</em>.<em>dddd</em> 的有符号数值, <em>dddd</em> 可以是一位或多位十进制数字. 小数点前的数字位数取决于整数部分的大小, 小数点后的数字位数取决于需求的精度. 例如, <code>Format("{:.2f}", 1)</code> 返回 <code class="no-highlight">1.00</code>.</td>
  </tr>
  <tr>
    <td><code>e</code></td>
    <td>Floating-point</td>
    <td>形如 [ - ]<em>d.dddd</em> e [<em>符号</em>]<em>dd[d]</em> 的有符号值, 这里的 <em>d</em> 是一位数字, <em>dddd</em> 是一位或多位数字, <em>dd[d]</em> 是两或三位数字, 取决于输出格式的定义和指数的大小, 这里的 <em>符号</em> 是 + 或 -. 例如, <code>Format("{:e}", 255)</code> 返回 <code class="no-highlight">2.550000e+002</code>.</td>
  </tr>
  <tr>
    <td><code>E</code></td>
    <td>Floating-point</td>
    <td>Identical to the <code>e</code> format except that E rather than e introduces the exponent.</td>
  </tr>
  <tr>
    <td><code>g</code></td>
    <td>Floating-point</td>
    <td>Signed values are displayed in <code>f</code> or <code>e</code> format, whichever is more compact for the given value and precision. The <code>e</code> format is used only when the exponent of the value is less than -4 or greater than or equal to the <em>precision</em> argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.</td>
  </tr>
  <tr>
    <td><code>G</code></td>
    <td>Floating-point</td>
    <td>Identical to the <code>g</code> format, except that E, rather than e, introduces the exponent (where appropriate).</td>
  </tr>
  <tr>
    <td><code>a</code></td>
    <td>Floating-point</td>
    <td>Signed hexadecimal double-precision floating-point value that has the form [?]0x<em>h.hhhh</em> <strong>p</strong>&plusmn;<em>dd</em>, where <em>h.hhhh</em> are the hex digits (using lower case letters) of the mantissa, and <em>dd</em> are one or more digits for the exponent. The precision specifies the number of digits after the point.</td>
  </tr>
  <tr>
    <td><code>A</code></td>
    <td>Floating-point</td>
    <td>Identical to the <code>a</code> format, except that P, rather than p, introduces the exponent.</td>
  </tr>
  <tr>
    <td><code>p</code></td>
    <td>Integer</td>
    <td>将参数显示为十六进制的内存地址. 例如, <code>Format("{:p}", 255)</code> 返回 <code class="no-highlight">000000FF</code>.</td>
  </tr>
  <tr>
    <td><code>s</code></td>
    <td>String</td>
    <td>Specifies a string. If the input value is numeric, it is automatically converted to a string before the <em>Width</em> and <em>Precision</em> arguments are applied.</td>
  </tr>
  <tr>
    <td><code>c</code></td>
    <td>Character code</td>
    <td>按照编码顺序输出一个单字符, 类似于 <code><a href="Chr.htm">Chr</a>(n)</code>. 如果输入值不在预期范围内将被回转. 例如, <code>Format("{:c}", 116)</code> 返回 <code>t</code>.</td>
  </tr>
</table>

<h2 id="Remarks">备注</h2>
<p>Unlike <a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions">printf</a>, size specifiers are not supported. All integers and floating-point input values are 64-bit.</p>

<h2 id="Related">相关</h2>
<p><a href="FormatTime.htm">FormatTime</a></p>

<h2 id="Examples">示例</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>
<em>; 简单替换</em>
s .= Format("{2}, {1}!`r`n", "World", "Hello")
<em>; 填充空格</em>
s .= Format("|{:-10}|`r`n|{:10}|`r`n", "Left", "Right")
<em>; 十六进制</em>
s .= Format("{1:#x} {2:X} 0x{3:x}`r`n", 3735928559, 195948557, 0)
<em>; 浮点数</em>
s .= Format("{1:0.3f} {1:.10f}", 4*ATan(1))

ListVars  <em>; 用 AutoHotkey 的主窗口显示等宽文本.</em>
WinWaitActive "ahk_class AutoHotkey"
ControlSetText(s, "Edit1")
WinWaitClose
</pre>
</div>

</body>
</html>